Summary

Adds a headless Slack workflow runner enabling AI-driven workflow execution triggered from Slack without a GUI. 9 modules (~1,410 LOC) with SQLite persistence, structured logging, graceful shutdown, and orphan worktree recovery.

🎫 Ticket 📐 Engineering 🧪 Test Plan

Motivation

The runner existed as a PoC that kept all session state in an in-memory Map, logged to the console with no file output, and left agent processes and worktrees behind on shutdown or crash. These gaps prevented it from being used for real workflow execution — a runner restart mid-workflow would lose all context, overnight crashes left no diagnostic trail, and orphaned worktrees accumulated on disk.

This PR hardens the runner for merge by adding SQLite state persistence (via node:sqlite, zero new dependencies), structured pino logging with daily file rotation, and full resource cleanup on both graceful shutdown and crash recovery.

Changes

• Session persistence (session-store.ts) — SQLite-backed session metadata storage using Node.js built-in node:sqlite; sessions survive runner restarts
• Session orchestration (session-manager.ts) — Lifecycle management for create → run → checkpoint relay → shutdown, with persistence at each state transition
• ACP client (acp-client.ts) — Cursor ACP agent process lifecycle and stdin/stdout protocol handling
• Slack integration (slack-bot.ts) — Slack Bolt app setup, slash-command routing, thread messaging via Socket Mode
• Checkpoint bridge (checkpoint-bridge.ts) — Bridges ACP checkpoint events to Slack interactive messages for human-in-the-loop approval
• Worktree isolation (worktree-manager.ts) — Git worktree creation/teardown per session; orphan sweep on startup removes stale wf-runner-* worktrees
• Configuration (config.ts) — Zod-validated config from environment variables
• Structured logging (logger.ts) — pino + pino-roll for rotating structured JSON log files with session context
• Entrypoint (index.ts) — Bootstrap, signal handling (SIGINT/SIGTERM), graceful shutdown orchestration
• Slack app manifest (docs/slack-app-manifest.yml) — Declarative Slack app configuration for the runner
• Setup guide (docs/runner-setup.md) — Installation and configuration instructions
• Tests — 5 test files, 43 unit tests (~920 LOC) covering session-manager, session-store, acp-client, checkpoint-bridge, and worktree-manager

Module Overview

Key Capabilities

• Slack-triggered execution — users invoke workflows via Slack slash commands; progress and checkpoints surface in threads
• Git worktree isolation — each workflow session gets its own worktree (wf-runner-<id>), preventing interference between concurrent runs
• SQLite state persistence — session metadata survives process restarts via node:sqlite
• Structured logging — pino with pino-roll for rotating log files; all events include session context
• Graceful shutdown — SIGINT/SIGTERM triggers shutdownAll() which cleans up active sessions, closes the DB, and stops the Slack listener
• Orphan worktree sweep — on startup, removes leftover wf-runner-* worktrees from prior unclean exits
• Input validation — Zod schema validation on config; regex validation on slash command arguments

📌 Submission Checklist

• Implementation complete (9 modules, ~1,410 LOC)
• Unit tests passing (43 tests across 5 files, ~920 LOC)
• TypeScript typecheck passing
• Strategic review passed
• All commits pushed to remote
• Slack app manifest included (docs/slack-app-manifest.yml)
• Setup guide included (docs/runner-setup.md)

🗹 TODO before merging

• Ready for review